Skip to main content

API Authentication

The API Layer is (so far) available only for partners. To authenticate the APIs, the following "Authorization" header must be added to the HTTP requests:

APIAuth {UUID}:{SIGNATURE}

where:

  • UUID is the partner Unique Identifier
  • SIGNATURE is a dynamic value that needs to be calculated by considering the partner SECRET_KEY, the current timestamp (DATE) and the current URL of the remothe method.

Authorization token creation​

As seen before, for create the token you have to put the partner UUID and then calculate the SIGNATURE. These are the steps to follow for create a SIGNATURE:

  1. A canonical string is first created using your HTTP headers containing the X-Authorization-Content-SHA256, request path and the date/time stamp. If X-Authorization-Content-SHA256 are not present, then a blank string is used in their place. If the timestamp isn't present, a valid HTTP date is automatically added to the request. The canonical string is computed as follows:
  canonical_string = "#{http method},#{X-Authorization-Content-SHA256},#{request URI},#{timestamp}"

e.g.,

  canonical_string = 'POST,,request_path,Tue, 30 May 2017 03:51:43 GMT'

IMPORTANT. Make sure to set the DATE into the header with the date that you'll use inside the canonical string.

  Date = 'Tue, 30 May 2017 03:51:43 GMT'

  1. This string is then used to create the signature which is a Base64 encoded SHA1 HMAC, using the partner secret key.

  2. This signature is then added as the Authorization HTTP header in the form:

Authorization = APIAuth "#{UUID}:#{signature from step 2}"

e.g.,

APIAuth 1qa2ws3e-1234-12er-qw12-123321ewqe21:=dsa100cdmsq=1e9fdslq

Below follows an example, written javascript, of a calculation used in POSTMAN (You should read this only like an hint, this snippet was used only for testing purpose):

const method = pm.request.method.toUpperCase();
const xAuth = pm.request.headers.get("X-Authorization-Content-SHA256") || '';
let url = pm.request.url.getPathWithQuery();

pm.collectionVariables.set("DATE", new Date().toUTCString()); // Set the DATE header variable (in POSTMAN)
const timestamp = pm.collectionVariables.get('DATE'); // Read the DATE variable (in POSTMAN)
const canonicalString = [method, xAuth, url, timestamp].join(",");
const secretKey = pm.collectionVariables.get("SECRET_KEY"); // Read SECRET_KEY variable (in POSTMAN) of the partner
const hmacEncodedStr = CryptoJS.HmacSHA1(canonicalString, secretKey);
const signature = hmacEncodedStr.toString(CryptoJS.enc.Base64);
pm.collectionVariables.set("SIGNATURE", signature); // Set the SIGNATURE variable (in POSTMAN)